Scanning Through a Job's Format Objects(IM:XP)

Inside Macintosh: QuickDraw GX Printing /: Chapter 3 - Page Formatting and Dialog Box Customization / Using Format Objects and Collection Items to Format Pages

Scanning Through a Job's Format Objects
QuickDraw GX allows you to scan through the format objects associated with a particular job. You can use the GXCountJobFormats function to obtain the number of format objects in a particular job object. If you want to examine or manipulate each format object for a job, you can use the GXForEachJobFormatDo function.

Note
You cannot use the GXForEachJobFormatDo function to modify the default format.
Listing 3-17 shows the GXForEachJobFormatDo function being called to execute the MyCheckMappingProc function on each format object.
Listing 3-17 Using the GXForEachJobFormatDo function
OSErr MyCheckAllFormatMappings(MyDocumentPtr myDocument)
{
   gxMapping   theMapping;

   /* Loop through each format, and check its mapping. */

   GXForEachJobFormatDo(myDocument->documentJob, 
                        MyCheckMappingProc, (void *) &theMapping);

   return GXGetJobError(myDocument->documentJob);
}
The GXForEachJobFormatDo function passes a pointer to the application-supplied function to execute and a pointer to the information that the application-supplied function returns. The prototype for the application-supplied function is as follows:
gxLoopStatus MyFormatFunction (gxFormat aFormat, void *refCon);
The first parameter, aFormat, is a reference to a format object. QuickDraw GX sets this parameter as it calls the function for each format object referenced by a job object. The second parameter, refCon, is a pointer to a reference constant through which data can be passed. The return value, gxLoopStatus, specifies whether the application-supplied function should be called again, allowing you to terminate the GXForEachJobFormatDo function early.
Listing 3-18 shows the application-supplied function, MyCheckMappingProc, that obtains scaling and orientation information for each format object associated with a particular job. For example, you can use this function to obtain scaling information when you need to adjust a ruler.
Listing 3-18 Obtaining scaling information on each format object
pascal gxLoopStatus MyCheckMappingProc(gxFormat aFormat, void 
                                                      *theMapping)
{
   /* 
      Get the mapping for the current format object, check it out, 
      and keep looping until all formats objects are accessed. 
   */
   GXGetFormatMapping(aFormat, (gxMapping *) theMapping);
      
   /*
      Your application could adjust rulers here, or do some
      other useful thing based on each format object's mapping.
   */
   ...
   return gxKeepLooping;
}
Note
For information about the gxMapping structure that contains scaling and rotation (orientation) information, see the mathematical functions chapter of Inside Macintosh: QuickDraw GX Environment and Utilities.